/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.flink.connector.jdbc;

import org.apache.flink.annotation.PublicEvolving;
import org.apache.flink.util.Preconditions;

import javax.annotation.Nullable;

import java.io.Serializable;
import java.util.Optional;

/** JDBC connection options. */
@PublicEvolving
public class JdbcConnectionOptions implements Serializable {

    private static final long serialVersionUID = 1L;

    protected final String url;
    @Nullable protected final String driverName;
    protected final int connectionCheckTimeoutSeconds;
    
    @Nullable protected final String username;
    
    @Nullable protected final String password;

    // 创建JDBC连接选项对象，并传递给JDBC连接器或其他相关组件。
    protected JdbcConnectionOptions(
            String url,
            @Nullable String driverName,
            @Nullable String username,
            @Nullable String password,
            int connectionCheckTimeoutSeconds) {

        // 使用Preconditions.checkArgument()方法
        // 检查连接检查超时时间是否大于 0
        Preconditions.checkArgument(connectionCheckTimeoutSeconds > 0);

        // 将传入的参数赋值给类的成员变量。
        this.url = Preconditions.checkNotNull(url, "jdbc url is empty");
        this.driverName = driverName;
        this.username = username;
        this.password = password;
        this.connectionCheckTimeoutSeconds = connectionCheckTimeoutSeconds;
    }

    public String getDbURL() {
        return url;
    }

    @Nullable
    public String getDriverName() {
        return driverName;
    }

    public Optional<String> getUsername() {
        return Optional.ofNullable(username);
    }

    // 使用 ofNullable()方法将密码字符串转换为 Optional对象，以避免空指针异常。
    // 如果密码不为 null，则返回包含密码的 Optional对象；否则返回一个空的 Optional对象。
    public Optional<String> getPassword() {
        return Optional.ofNullable(password);
    }

    public int getConnectionCheckTimeoutSeconds() {
        return connectionCheckTimeoutSeconds;
    }

    /** Builder for {@link JdbcConnectionOptions}. */
    public static class JdbcConnectionOptionsBuilder {
        private String url;
        private String driverName;
        private String username;
        private String password;

        // 连接检查超时时间，用于检测 TCP连接是否建立成功的超时时间,默认 60s
        private int connectionCheckTimeoutSeconds = 60;

        public JdbcConnectionOptionsBuilder withUrl(String url) {
            this.url = url;
            return this;
        }

        public JdbcConnectionOptionsBuilder withDriverName(String driverName) {
            this.driverName = driverName;
            return this;
        }

        public JdbcConnectionOptionsBuilder withUsername(String username) {
            this.username = username;
            return this;
        }

        public JdbcConnectionOptionsBuilder withPassword(String password) {
            this.password = password;
            return this;
        }

        /**
         * Set the maximum timeout between retries, default is 60 seconds.
         *
         * @param connectionCheckTimeoutSeconds 
         * the timeout seconds, shouldn't smaller than 1 second.
         * 
         *  withConnectionCheckTimeoutSeconds方法是一个链式调用的方法，
         *  它接受一个整型类型的参数 connectionCheckTimeoutSeconds，
         *  用于设置 JDBC连接检查超时时间。                               
         */
        public JdbcConnectionOptionsBuilder withConnectionCheckTimeoutSeconds(
                int connectionCheckTimeoutSeconds) {

            // 将传入的参数赋值给成员变量 this.connectionCheckTimeoutSeconds，
            this.connectionCheckTimeoutSeconds = connectionCheckTimeoutSeconds;

            // 返回当前对象this，以便进行链式调用。 
            return this;
        }

        // 使用构建器中收集的参数创建一个新的 JdbcConnectionOptions对象，并返回该对象。
        public JdbcConnectionOptions build() {

            return new JdbcConnectionOptions(
                    url, driverName, username, password, connectionCheckTimeoutSeconds);
        }
    }
}
